PyStack

PyStack is a tool that uses forbidden magic to let you inspect the stack frames of a running Python process or a Python core dump, to learn easily and quickly what it is doing (or what it was doing when it crashed) without having to interpret nasty CPython internals.

What PyStack can do

PyStack has the following amazing features:

• 💻 Works with both running processes and core dump files.

• 🧵 Shows if each thread currently holds the Python GIL, is waiting to acquire it, or is currently dropping it.

• 🗑️ Shows if a thread is running a garbage collection cycle.

• 🐍 Optionally shows native function calls, as well as Python ones. In this mode, PyStack prints the native stack trace (C/C++/Rust function calls), except that the calls to Python callables are replaced with frames showing the Python code being executed, instead of showing the internal C code the interpreter used to make the call.

• 🔍 Automatically demangles symbols shown in the native stack.

• 📈 Includes calls to inlined functions in the native stack whenever enough debug information is available.

• 🔍 Optionally shows the values of local variables and function arguments in Python stack frames.

• 🔒 Safe to use on running processes. PyStack does not modify any memory or execute any code in a process that is running. It simply attaches just long enough to read some of the process’s memory.

• ⚡ Optionally, it can perform a Python stack analysis without pausing the process at all. This minimizes impact to the debugged process, at the cost of potentially failing due to data races.

• 🚀 Super fast! It can analyze core files 10x faster than general-purpose tools like GDB.

• 🎯 Even works with aggressively optimized Python interpreter binaries.

• 🔍 Even works with Python interpreters’ binaries that do not have symbols or debug information (Python stack only).

• 💥 Tolerates memory corruption well. Even if the process crashed due to memory corruption, PyStack can usually reconstruct the stack.

• 💼 Self-contained: it does not depend on external tools or programs other than the Python interpreter used to run PyStack itself.

Contents

• Analyzing processes
  • Positional Arguments
  • Named Arguments
  • Operation modes
  • Interpreter finalization
• Analyzing core dumps
  • Positional Arguments
  • Named Arguments
  • Providing the executable
  • Core file information
  • Origin of the core file
  • Analyzing core files in a different machine
  • Analyzing core files with insufficient information
• Customizing the reports
  • Native traces
  • Locals

Indices and tables

• Index

• Search Page